<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Add and remove nodes in your cluster | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="setup.html" title="Set up Elasticsearch">
<link rel="prev" href="cluster-fault-detection.html" title="Cluster fault detection">
<link rel="next" href="restart-cluster.html" title="Full-cluster restart and rolling restart">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="setup.html">Set up Elasticsearch</a></span>
»
<span class="breadcrumb-node">Add and remove nodes in your cluster</span>
</div>
<div class="navheader">
<span class="prev">
<a href="cluster-fault-detection.html">« Cluster fault detection</a>
</span>
<span class="next">
<a href="restart-cluster.html">Full-cluster restart and rolling restart »</a>
</span>
</div>
<div class="chapter">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="add-elasticsearch-nodes"></a>Add and remove nodes in your cluster<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/setup/add-nodes.asciidoc">edit</a>
</h2>
</div></div></div>
<p>When you start an instance of Elasticsearch, you are starting a <em>node</em>. An Elasticsearch <em>cluster</em>
is a group of nodes that have the same <code class="literal">cluster.name</code> attribute. As nodes join
or leave a cluster, the cluster automatically reorganizes itself to evenly
distribute the data across the available nodes.</p>
<p>If you are running a single instance of Elasticsearch, you have a cluster of one node.
All primary shards reside on the single node. No replica shards can be
allocated, therefore the cluster state remains yellow. The cluster is fully
functional but is at risk of data loss in the event of a failure.</p>
<div class="imageblock">
<div class="content">
<img src="setup/images/elas_0202.png" alt="A cluster with one node and three primary shards">
</div>
</div>
<p>You add nodes to a cluster to increase its capacity and reliability. By default,
a node is both a data node and eligible to be elected as the master node that
controls the cluster. You can also configure a new node for a specific purpose,
such as handling ingest requests. For more information, see
<a class="xref" href="modules-node.html" title="Node">Nodes</a>.</p>
<p>When you add more nodes to a cluster, it automatically allocates replica shards.
When all primary and replica shards are active, the cluster state changes to
green.</p>
<div class="imageblock">
<div class="content">
<img src="setup/images/elas_0204.png" alt="A cluster with three nodes">
</div>
</div>
<p>You can run multiple nodes on your local machine in order to experiment with how
an Elasticsearch cluster of multiple nodes behaves. To add a node to a cluster running on
your local machine:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
Set up a new Elasticsearch instance.
</li>
<li class="listitem">
Specify the name of the cluster with the <code class="literal">cluster.name</code> setting in
<code class="literal">elasticsearch.yml</code>. For example, to add a node to the <code class="literal">logging-prod</code> cluster,
add the line <code class="literal">cluster.name: "logging-prod"</code> to <code class="literal">elasticsearch.yml</code>.
</li>
<li class="listitem">
Start Elasticsearch. The node automatically discovers and joins the specified cluster.
</li>
</ol>
</div>
<p>To add a node to a cluster running on multiple machines, you must also
<a class="xref" href="discovery-settings.html#unicast.hosts" title="discovery.seed_hosts">set <code class="literal">discovery.seed_hosts</code></a> so that the new node can discover
the rest of its cluster.</p>
<p>For more information about discovery and shard allocation, see
<a class="xref" href="modules-discovery.html" title="Discovery and cluster formation"><em>Discovery and cluster formation</em></a> and <a class="xref" href="modules-cluster.html" title="Cluster-level shard allocation and routing settings">Cluster-level shard allocation and routing settings</a>.</p>
<h3>
<a id="add-elasticsearch-nodes-master-eligible"></a>Master-eligible nodes<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/setup/add-nodes.asciidoc">edit</a>
</h3>
<p>As nodes are added or removed Elasticsearch maintains an optimal level of fault
tolerance by automatically updating the cluster’s <em>voting configuration</em>, which
is the set of <a class="xref" href="modules-node.html#master-node" title="Master-eligible node">master-eligible nodes</a> whose responses are counted
when making decisions such as electing a new master or committing a new cluster
state.</p>
<p>It is recommended to have a small and fixed number of master-eligible nodes in a
cluster, and to scale the cluster up and down by adding and removing
master-ineligible nodes only. However there are situations in which it may be
desirable to add or remove some master-eligible nodes to or from a cluster.</p>
<h4>
<a id="modules-discovery-adding-nodes"></a>Adding master-eligible nodes<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/setup/add-nodes.asciidoc">edit</a>
</h4>
<p>If you wish to add some nodes to your cluster, simply configure the new nodes
to find the existing cluster and start them up. Elasticsearch adds the new nodes
to the voting configuration if it is appropriate to do so.</p>
<p>During master election or when joining an existing formed cluster, a node
sends a join request to the master in order to be officially added to the
cluster. You can use the <code class="literal">cluster.join.timeout</code> setting to configure how long a
node waits after sending a request to join a cluster. Its default value is <code class="literal">30s</code>.
See <a class="xref" href="modules-discovery-settings.html" title="Discovery and cluster formation settings">Discovery and cluster formation settings</a>.</p>
<h4>
<a id="modules-discovery-removing-nodes"></a>Removing master-eligible nodes<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/setup/add-nodes.asciidoc">edit</a>
</h4>
<p>When removing master-eligible nodes, it is important not to remove too many all
at the same time. For instance, if there are currently seven master-eligible
nodes and you wish to reduce this to three, it is not possible simply to stop
four of the nodes at once: to do so would leave only three nodes remaining,
which is less than half of the voting configuration, which means the cluster
cannot take any further actions.</p>
<p>More precisely, if you shut down half or more of the master-eligible nodes all
at the same time then the cluster will normally become unavailable. If this
happens then you can bring the cluster back online by starting the removed
nodes again.</p>
<p>As long as there are at least three master-eligible nodes in the cluster, as a
general rule it is best to remove nodes one-at-a-time, allowing enough time for
the cluster to <a class="xref" href="modules-discovery-quorums.html" title="Quorum-based decision making">automatically adjust</a> the voting
configuration and adapt the fault tolerance level to the new set of nodes.</p>
<p>If there are only two master-eligible nodes remaining then neither node can be
safely removed since both are required to reliably make progress. To remove one
of these nodes you must first inform Elasticsearch that it should not be part of the
voting configuration, and that the voting power should instead be given to the
other node. You can then take the excluded node offline without preventing the
other node from making progress. A node which is added to a voting
configuration exclusion list still works normally, but Elasticsearch tries to remove it
from the voting configuration so its vote is no longer required. Importantly,
Elasticsearch will never automatically move a node on the voting exclusions list back
into the voting configuration. Once an excluded node has been successfully
auto-reconfigured out of the voting configuration, it is safe to shut it down
without affecting the cluster’s master-level availability. A node can be added
to the voting configuration exclusion list using the
<a class="xref" href="voting-config-exclusions.html" title="Voting configuration exclusions API">Voting configuration exclusions</a> API. For example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console"># Add node to voting configuration exclusions list and wait for the system
# to auto-reconfigure the node out of the voting configuration up to the
# default timeout of 30 seconds
POST /_cluster/voting_config_exclusions/node_name

# Add node to voting configuration exclusions list and wait for
# auto-reconfiguration up to one minute
POST /_cluster/voting_config_exclusions/node_name?timeout=1m</pre>
</div>
<div class="console_widget" data-snippet="snippets/39.console"></div>
<p>The node that should be added to the exclusions list is specified using
<a class="xref" href="cluster.html#cluster-nodes" title="Node specification">node filters</a> in place of <code class="literal">node_name</code> here. If a call to the
voting configuration exclusions API fails, you can safely retry it.  Only a
successful response guarantees that the node has actually been removed from the
voting configuration and will not be reinstated. If it’s the active master that
was removed from the voting configuration, then it will abdicate to another
master-eligible node that’s still in the voting configuration, if such a node
is available.</p>
<p>Although the voting configuration exclusions API is most useful for down-scaling
a two-node to a one-node cluster, it is also possible to use it to remove
multiple master-eligible nodes all at the same time. Adding multiple nodes to
the exclusions list has the system try to auto-reconfigure all of these nodes
out of the voting configuration, allowing them to be safely shut down while
keeping the cluster available. In the example described above, shrinking a
seven-master-node cluster down to only have three master nodes, you could add
four nodes to the exclusions list, wait for confirmation, and then shut them
down simultaneously.</p>
<div class="note admon">
<div class="icon"></div>
<div class="admon_content">
<p>Voting exclusions are only required when removing at least half of the
master-eligible nodes from a cluster in a short time period. They are not
required when removing master-ineligible nodes, nor are they required when
removing fewer than half of the master-eligible nodes.</p>
</div>
</div>
<p>Adding an exclusion for a node creates an entry for that node in the voting
configuration exclusions list, which has the system automatically try to
reconfigure the voting configuration to remove that node and prevents it from
returning to the voting configuration once it has removed. The current list of
exclusions is stored in the cluster state and can be inspected as follows:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_cluster/state?filter_path=metadata.cluster_coordination.voting_config_exclusions</pre>
</div>
<div class="console_widget" data-snippet="snippets/40.console"></div>
<p>This list is limited in size by the <code class="literal">cluster.max_voting_config_exclusions</code>
setting, which defaults to <code class="literal">10</code>. See <a class="xref" href="modules-discovery-settings.html" title="Discovery and cluster formation settings">Discovery and cluster formation settings</a>. Since
voting configuration exclusions are persistent and limited in number, they must
be cleaned up. Normally an exclusion is added when performing some maintenance
on the cluster, and the exclusions should be cleaned up when the maintenance is
complete. Clusters should have no voting configuration exclusions in normal
operation.</p>
<p>If a node is excluded from the voting configuration because it is to be shut
down permanently, its exclusion can be removed after it is shut down and removed
from the cluster. Exclusions can also be cleared if they were created in error
or were only required temporarily:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console"># Wait for all the nodes with voting configuration exclusions to be removed from
# the cluster and then remove all the exclusions, allowing any node to return to
# the voting configuration in the future.
DELETE /_cluster/voting_config_exclusions

# Immediately remove all the voting configuration exclusions, allowing any node
# to return to the voting configuration in the future.
DELETE /_cluster/voting_config_exclusions?wait_for_removal=false</pre>
</div>
<div class="console_widget" data-snippet="snippets/41.console"></div>
</div>
<div class="navfooter">
<span class="prev">
<a href="cluster-fault-detection.html">« Cluster fault detection</a>
</span>
<span class="next">
<a href="restart-cluster.html">Full-cluster restart and rolling restart »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
